feat(v1): make FetchBlock and ReadData single-item operations - #208
Open
carbolymer wants to merge 1 commit into
Open
feat(v1): make FetchBlock and ReadData single-item operations#208carbolymer wants to merge 1 commit into
carbolymer wants to merge 1 commit into
Conversation
carbolymer
force-pushed
the
sync-fetchblock-single-block
branch
2 times, most recently
from
July 20, 2026 15:40
16d52e3 to
e3a8517
Compare
4 tasks
carbolymer
force-pushed
the
sync-fetchblock-single-block
branch
2 times, most recently
from
August 20, 2026 13:21
6e0cec4 to
32bcb6a
Compare
carbolymer
force-pushed
the
sync-fetchblock-single-block
branch
from
August 20, 2026 13:24
32bcb6a to
22a60f3
Compare
carbolymer
added a commit
to IntersectMBO/cardano-api
that referenced
this pull request
Aug 20, 2026
The single-item FetchBlock variant moved to the upcoming utxorpc v1 (utxorpc/spec#208 was retargeted there), so v1beta keeps the repeated request refs and response blocks. Regenerate the proto-lens Sync modules and make the handler fetch every referenced block, failing the whole call with NOT_FOUND naming the first missing ref's slot and header hash, matching Dolos's all-or-nothing behaviour. Mark the changelog fragment as breaking accordingly.
scarmuega
approved these changes
Aug 25, 2026
carbolymer
added a commit
to IntersectMBO/cardano-api
that referenced
this pull request
Aug 27, 2026
The single-item FetchBlock variant moved to the upcoming utxorpc v1 (utxorpc/spec#208 was retargeted there), so v1beta keeps the repeated request refs and response blocks. Regenerate the proto-lens Sync modules and make the handler fetch every referenced block, failing the whole call with NOT_FOUND naming the first missing ref's slot and header hash, matching Dolos's all-or-nothing behaviour. Mark the changelog fragment as breaking accordingly.
carbolymer
added a commit
to IntersectMBO/cardano-api
that referenced
this pull request
Aug 27, 2026
The single-item FetchBlock variant moved to the upcoming utxorpc v1 (utxorpc/spec#208 was retargeted there), so v1beta keeps the repeated request refs and response blocks. Regenerate the proto-lens Sync modules and make the handler fetch every referenced block, failing the whole call with NOT_FOUND naming the first missing ref's slot and header hash, matching Dolos's all-or-nothing behaviour. Mark the changelog fragment as breaking accordingly.
carbolymer
added a commit
to IntersectMBO/cardano-api
that referenced
this pull request
Aug 27, 2026
The single-item FetchBlock variant moved to the upcoming utxorpc v1 (utxorpc/spec#208 was retargeted there), so v1beta keeps the repeated request refs and response blocks. Regenerate the proto-lens Sync modules and make the handler fetch every referenced block, failing the whole call with NOT_FOUND naming the first missing ref's slot and header hash, matching Dolos's all-or-nothing behaviour. Mark the changelog fragment as breaking accordingly.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
repeatedfromFetchBlockRequest.refandFetchBlockResponse.block, making FetchBlock a single-block operation.repeatedfromReadDataRequest.keysandReadDataResponse.values(nowkeyandvalue), making ReadData a single-datum operation.v1package;v1betaandv1alphaare untouched.Motivation
These RPCs are per-item lookups, but the batched responses had no per-item error channel.
When one item could not be resolved, a server could only fail the whole call or silently omit the item, and the client could not tell omission from an error.
Existing implementations confirm the problem: Dolos fails the whole FetchBlock call on the first unresolvable ref, and dingo aborts both FetchBlock and ReadData on the first miss.
With single-item requests, the gRPC status code applies unambiguously to the one requested item.
Batching also bought nothing here, on either axis:
This follows the same approach as #163, which made
SubmitTxandEvalTxsingular.Why ReadUtxos is not following suit
ReadUtxos is the only one of the three that queries mutable ledger state, and its
repeated keysfield buys two things single-item requests cannot replicate:GetUTxOByTxIn), and implementations use it: cardano-node-api forwards the whole key list in a single N2C query, and dingo resolves all refs in one batched SQL query. Splitting into singles turns one lookup into N.ledger_tiponly lets a client detect after the fact that its reads straddled a tip change.The absent-vs-failed ambiguity described above affects ReadUtxos too, but it can be fixed without giving up batching: each response item could state explicitly whether the key was
found(carrying the UTxO) ormissing(echoing the key), so absence becomes an answer instead of a silence.That is left out of scope for this PR.
Breaking change
This is a wire-incompatible change to the
v1package.v1is freshly initialised (565b990) and unreleased, so no published consumers are affected;v1betaandv1alphaare untouched.